Expose world helpers via workflow/api (v2) #259

artimath · 2025-11-07T11:32:12Z

PR: Expose world helpers via workflow/api (v2)

Summary

Surface getWorld plus every World helper (runs/steps/events/hooks/queue/streams/start) directly from workflow/api, so application code can manage runs without reimplementing createWorld.
Add Vitest coverage that stubs setWorld to assert each helper delegates correctly and specifically exercises the “list runs then cancel” flow requested for Next.js/server usage.
Document the new API via a dedicated “World helpers” reference page, updated foundations guide example, and API index entry; include testing guidance about swapping worlds.
Record the change with a Changeset so release automation bumps the workflow package.

Use Cases Addressed

Programmatic run management: Next.js routes (or any server code) can list, inspect, pause/resume, or cancel active runs using listRuns, cancelRun, etc., without importing from workflow/runtime.
Accessing the default world: Users asking “is there a public API to access the active World?” can now call getWorld() from workflow/api, matching CLI behavior across dev/test/prod setups.
Queue/stream control: Advanced tooling can enqueue messages or stream data via the same helpers the runtime uses (queue, createQueueHandler, writeToStream, etc.).
Testability: Teams can stub setWorld in tests while still using the exported helpers, ensuring parity with production behavior.

Implementation Details

packages/workflow/src/api.ts now imports the relevant types from @workflow/world, re-exports them, and defines thin wrappers for every World subfunction plus startWorld.
Added @workflow/world to packages/workflow/package.json dependencies and synced pnpm-lock.yaml.
Created packages/workflow/src/api.test.ts with full delegation coverage and the “list -> cancel” scenario.
Authored docs/content/docs/api-reference/workflow-api/world.mdx, updated the API index cards, and inserted a new “Programmatically list and control runs” section in starting-workflows.mdx.
Added .changeset/expose-world-helpers.md so the workflow package gets a patch bump.

Verification

pnpm --filter workflow test -- src/api.test.ts
pnpm --filter workflow typecheck
pnpm biome check packages/workflow/src/api.ts packages/workflow/src/api.test.ts

Notes

The PR remains in draft status until review; description mirrored here for convenience.

changeset-bot · 2025-11-07T11:32:16Z

🦋 Changeset detected

Latest commit: 60bb0b4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
workflow	Patch
@workflow/ai	Patch
@workflow/world-testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-11-07T11:32:19Z

@artimath is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

VaguelySerious

Thanks for contributing!

A lot of the documentation changes are great. We're not sure yet if we want to re-export all the functions top-level, instead, for now, I think we should document getWorld more and maybe make it available under /api too. Since users might eventually run into the world concept anyway, it's less confusing if there's a single way to interact with the API.

We'd be happy to merge this, if those changes are implemented, making this a mostly documentation-focused PR. If so, please also ensure DCO passes on your final commit

VaguelySerious · 2025-11-11T18:53:25Z

docs/content/docs/api-reference/workflow-api/index.mdx

        Get workflow run status and metadata without waiting for completion.
    </Card>
+    <Card href="/docs/api-reference/workflow-api/world" title="World helpers">
+        Access the World singleton plus list/cancel APIs for runs, steps, events, and hooks.


Suggested change

Access the World singleton plus list/cancel APIs for runs, steps, events, and hooks.

Access the World API for programmatic access to run, step, event, and hook entities.

VaguelySerious · 2025-11-11T18:53:33Z

docs/content/docs/api-reference/workflow-api/world.mdx

+
+This works the same way in development and production—just make sure the usual `WORKFLOW_*` environment variables are present so the correct world implementation can be chosen.
+
+## Helper catalog


I think we might want to generate these from the interface, so they don't get outdated. For now, we could just link to the latest interface.ts file in the npm package?

VaguelySerious · 2025-11-11T18:55:13Z

docs/content/docs/foundations/starting-workflows.mdx


+### Programmatically list and control runs
+
+If you want to show workflow progress directly in your product UI—or let trusted operators retry or cancel work—you can now call the same administrative helpers the CLI uses, straight from `workflow/api`.


Suggested change

If you want to show workflow progress directly in your product UI—or let trusted operators retry or cancel work—you can now call the same administrative helpers the CLI uses, straight from `workflow/api`.

If you want to show workflow progress directly in your product UI, or let trusted operators retry or cancel runs, you can call `getWorld()` to access the full low-level API. See the [World helpers reference](/docs/api-reference/workflow-api/world) for a list of capabilities.

VaguelySerious · 2025-11-11T18:56:29Z

docs/content/docs/foundations/starting-workflows.mdx

 }
 ```

+### Programmatically list and control runs


Suggested change

### Programmatically list and control runs

### Programmatically query and control runs

VaguelySerious · 2025-11-11T18:58:19Z

docs/content/docs/foundations/starting-workflows.mdx

+If you want to show workflow progress directly in your product UI—or let trusted operators retry or cancel work—you can now call the same administrative helpers the CLI uses, straight from `workflow/api`.
+
+```typescript lineNumbers
+import { listRuns, cancelRun } from 'workflow/api';


This example should be moved to /docs/api-reference/workflow-api/world and use getWorld instead

VaguelySerious · 2025-11-11T18:59:27Z

packages/workflow/src/api.ts

+/**
+ * Creates a workflow run using the configured World implementation.
+ */
+export function createRun(


We should encourage users to use getWorld() directly instead, which makes the API more discoverable (i.e. what actions are available on a run? Just type world.runs. to find the list) and allows us to skip the duplication in this file

VaguelySerious · 2025-11-11T19:00:06Z

packages/workflow/src/api.ts

  type Event,
  getHookByToken,
  getRun,
+  getWorld,


It think it'd be fine to re-export getWorld and createWorld from src/api for discoverability (in addition to the export already on runtime)

VaguelySerious · 2025-11-11T19:00:58Z

docs/content/docs/api-reference/workflow-api/world.mdx

+
+# Accessing the World singleton
+
+> “Is there any public API to access the active default World? I'd like to be able to list active runs in my app, like I can via the CLI. I could store them myself, but if there is an API for this that works across testing and deployment, that'd be even better!”


Let's skip this

artimath marked this pull request as draft November 7, 2025 11:32

artimath force-pushed the feature/world-helpers-pr2 branch 2 times, most recently from f0c5331 to ac7b480 Compare November 7, 2025 11:46

feat: expose world helpers via workflow/api

60bb0b4

artimath force-pushed the feature/world-helpers-pr2 branch from ac7b480 to 60bb0b4 Compare November 7, 2025 11:47

artimath marked this pull request as ready for review November 7, 2025 12:47

VaguelySerious requested changes Nov 11, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Expose world helpers via workflow/api (v2) #259

Expose world helpers via workflow/api (v2) #259

Uh oh!

artimath commented Nov 7, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Nov 7, 2025 •

edited

Loading

Uh oh!

vercel bot commented Nov 7, 2025

Uh oh!

VaguelySerious left a comment

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

VaguelySerious Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	Access the World singleton plus list/cancel APIs for runs, steps, events, and hooks.
	Access the World API for programmatic access to run, step, event, and hook entities.


		This works the same way in development and production—just make sure the usual `WORKFLOW_*` environment variables are present so the correct world implementation can be chosen.

		## Helper catalog


		### Programmatically list and control runs

		If you want to show workflow progress directly in your product UI—or let trusted operators retry or cancel work—you can now call the same administrative helpers the CLI uses, straight from `workflow/api`.

	### Programmatically list and control runs
	### Programmatically query and control runs


		# Accessing the World singleton

		> “Is there any public API to access the active default World? I'd like to be able to list active runs in my app, like I can via the CLI. I could store them myself, but if there is an API for this that works across testing and deployment, that'd be even better!”

Expose world helpers via workflow/api (v2) #259

Are you sure you want to change the base?

Expose world helpers via workflow/api (v2) #259

Uh oh!

Conversation

artimath commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR: Expose world helpers via workflow/api (v2)

Summary

Use Cases Addressed

Implementation Details

Verification

Notes

Uh oh!

changeset-bot bot commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Nov 7, 2025

Uh oh!

VaguelySerious left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

artimath commented Nov 7, 2025 •

edited

Loading

changeset-bot bot commented Nov 7, 2025 •

edited

Loading